[B5] Support for migrating report views to Bootstrap 5 #35648

biyeun · 2025-01-21T15:58:48Z

Technical Summary

Recommended: Review Commit-by-Commit

This PR does a few things, but it does not migrate ANY existing reports yet (example migration is here). I carefully made sure the changes in this PR would NOT threaten production workflows, so that this PR is safe to merge without QA. I have put the branch, including two report migrations (ApplicationStatusReport and CaseListReport) on staging.

This PR:

Sets up the infrastructure behind Report Views to support migrating that report to bootstrap5. This means a way to enable a bootstrap 5 mode for the report, in this case setting use_bootstrap5 = True for that report view. This makes sure that bootstrap5 versions of base report and filter templates are correctly loaded.
Upgrades datatables_config to be compatible with Datatables 1.10+ style parameters. We need to use a new version of Datatables in order to support bootstrap 5 styling. The new version of datatables introduces SIGNIFICANT changes into how the request QueryString object looks when a datatables-initiated request is made. These changes means I had to get creative by creating a request parameter "interpreter" in order to get the desired value from filter parameters inserted into a datatables pagination request.
Updates HTML formatting and any bootstrap 5 related updates to core/base report base templates and filters. This PR does NOT make required updates to ALL filters and report templates. The idea is that these templates will be updated as each report is migrated. See this diff for an example of what migrating two reports (ApplicationStatusReport and CaseListReport) looks like:
bmb/b5-reports...bmb/b5-reports-initial-migration
Updates core javascript so that the most basic filters/reports can load without error. I tested the JS updates with migrating CaseListReport and ApplicationStatusReport (has an email report button). I very INTENTIONALLY left off the work needed to migrate datespan filters, as I was worried that work would not allow me to finish this PR in the time I had set aside for it as part of dependacat duties. My concern is that the datespan filter javascript needs to move toward using Tempus Dominus, and I think there might be additional tweaks required. I wanted to narrow the scope of this PR to fixing the datatables 1.10+ and report view setup to handle loading ANY report.
I introduced debugging tools (activated by setting debug_bootstrap5 = True on the report) to make sure it's easier to figure out what filters and templates need migration—and to ensure no feature flagged filters are missed! Alongside this work is a new migration helper tool ./manage.py complete_bootstrap5_report <ReportClassName> to keep track of what reports, filters, and filter templates have already been migrated. It also ensures that child reports are non un-intentionally migrated (e.g. CaseListExplorer, which inherits from CaseListReport is not migrated).
Lastly, updates to the Bootstrap 5 Migration guide for migrating report views with a 4-step routine to ensure a report view is fully migrated to Bootstrap 5.

Read the Bootstrap 5 Migration Guide additions here

Safety Assurance

Safety story

The changes here were carefully applied so as to not affect production workflows. I've put the branch on staging to ensure core functionality is not affected.

Automated test coverage

Yes, where appropriate I've added tests.

QA Plan

I believe the changes here are isolated enough that QA is not needed, however I will be triggering QA for the first two migrated reports here, which will come as a later PR. I hope to not keep this PR unmerged for too long to avoid merge conflicts with folks working in overlapping areas.

Rollback instructions

depending on how long we wait to roll back, the bootstrap 5 diffs might make it cumbersome to revert as a whole. However each individual commit is revertable.

This PR can be reverted after deploy with no further considerations

Labels & Review

Risk label is set correctly
The set of people pinged as reviewers is appropriate for the level of risk of the change

biyeun · 2025-01-21T16:28:35Z

I intentionally ignored un-related code that had lint flags because it resulted in unnecessary merge conflicts with current work on staging, as I had to touch quite a few different files with the request_params changes

biyeun · 2025-01-21T16:31:55Z

corehq/apps/hqwebapp/utils/bootstrap/reports/debug.py

+    return instance.__class__.__name__
+
+
+def reports_bootstrap5_template_debugger(report_instance):


example output of what it looks like in the console:

biyeun · 2025-01-21T16:35:19Z

corehq/apps/hqwebapp/utils/bootstrap/reports/stats.py

+from corehq.motech.repeaters.views import DomainForwardingRepeatRecords
+
+
+ALL_REPORTS = [


I'm not too concerned about enforcing that this list is kept up-to-date as new reports are added. I think it will be clear to anyone who goes to a report missing in this list to add it here if they migrate the report and try to run complete_bootstrap5_report TheirReportView.

biyeun · 2025-01-21T17:08:59Z

corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html

@@ -31,6 +31,7 @@ <h5 class="my-2 ms-3">On this page</h5>
          <li><a href="#un-split-view-files">Un-Split View Files</a></li>


read the updated guide on staging:
https://staging.commcarehq.org/styleguide/b5/migration/#migrating-report-views

nospame · 2025-01-22T16:33:45Z

corehq/apps/reports/generic.py

        if self.asynchronous:
-            return self.base_template_async or "reports/async/bootstrap3/default.html"
+            return self.base_template_async or default_path


should this use get_bootstrap5_path?

nospame · 2025-01-22T16:50:26Z

corehq/apps/hqwebapp/management/commands/complete_bootstrap5_report.py

+        mark_report_as_complete(report_class.__name__)
+        self.suggest_commit_message(f"Completed report: {report_class.__name__}.")
+
+    def is_filter_migrated(self, field, filter_class, migrated_filter_templates):


A more descriptive name, like flag_unmigrated_filter or is_filter_migrated_prompt?

biyeun · 2025-01-22T17:54:23Z

^removed the build bootstrap5 diffs commit as that's going to cause a few merge conflicts with the smaller PRs i'm branching off from this!

orangejenny · 2025-01-22T18:34:58Z

#35651 should resolve the javascript lint errors (although it will likely also introduce new ones)

biyeun · 2025-01-23T12:37:59Z

NOTE: I'm actively rebasing the commits here to reduce the size of this PR and move commits out of it into smaller PRs. we will resume group review on monday :)

for bootstrap5, datatables > 1.10

fix typo with tooltip usage

biyeun added product/invisible Change has no end-user visible impact dependencies/javascript Change in javascript dependency. labels Jan 21, 2025

biyeun requested review from millerdev, orangejenny and a team January 21, 2025 15:58

biyeun requested review from calellowitz, esoergel and kaapstorm as code owners January 21, 2025 15:58

dimagimon added the Risk: Medium Change affects files that have been flagged as medium risk. label Jan 21, 2025

biyeun changed the title ~~[B5] Support for migrating report views to~~ [B5] Support for migrating report views to Bootstrap 5 Jan 21, 2025

biyeun force-pushed the bmb/b5-reports branch from bb63f2a to 74a3748 Compare January 21, 2025 16:11

biyeun commented Jan 21, 2025

View reviewed changes

nospame reviewed Jan 22, 2025

View reviewed changes

biyeun force-pushed the bmb/b5-reports branch from 74a3748 to 6530376 Compare January 22, 2025 17:53

biyeun mentioned this pull request Jan 22, 2025

[B5] Update SCSS for reports (and fix its breadcrumbs) #35659

Merged

3 tasks

dimagimon removed the Risk: Medium Change affects files that have been flagged as medium risk. label Jan 22, 2025

biyeun force-pushed the bmb/b5-reports branch 2 times, most recently from 665fc6a to e7f2fa8 Compare January 23, 2025 12:36

biyeun added 5 commits January 23, 2025 16:17

add utils for bootstrap 5 paths

5559228

add ability to set a report to use_bootstrap5

d88dce2

pass use_bootstrap5 status to filters so the right template is chosen

dc75863

create utility to get filter class individually

8eebc73

B5: add report debug tools and way to track completion

1920056

biyeun added 23 commits January 23, 2025 16:17

update bootstrap 5 migration guide for migrating report views

6a1e31e

datatables_config (B5) - update how datatables gets imported

aed103c

update datatables_config (B5) to work with datatables 1.10+

526871e

loading template no longer supported in datatables 1.10+

fd531a8

add todo about custom sort for future investigation

1b6784a

update how reports handles datatables server side params after 1.10

ea5459f

update the data returned by reports view to datatables

27a510b

for bootstrap5, datatables > 1.10

update how sorting block in generated for datatables > 1.10

b194f34

update request parameter fetching for reports using Datatables 1.10+

67edabf

replace hide css class with d-none

531232d

fix Popover initialization

2592342

update bootstrap5 tooltip

64acb67

fix typo with tooltip usage

update bootstrap5 plugins

9d81717

update tooltip bootstrap5 component usage

bb6b277

update bootstrap3 path refs in bootstrap5 files

bef4052

update field and form group html

97f1717

update stateful button usage

7b7bdff

fix popover usage

c54b538

update visible class/state for filter accordion on B5 pages

a65804f

update label to badge (bootstrap 5) in js usage

5564c33

translate

aead15e

update formatting and migrate core report templates to bootstrap5

a337c15

have email report form support usage with bootstrap 5 pages

d1323b1

biyeun force-pushed the bmb/b5-reports branch from e7f2fa8 to d1323b1 Compare January 23, 2025 15:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[B5] Support for migrating report views to Bootstrap 5 #35648

[B5] Support for migrating report views to Bootstrap 5 #35648

biyeun commented Jan 21, 2025 •

edited

Loading

biyeun commented Jan 21, 2025

biyeun Jan 21, 2025

biyeun Jan 21, 2025

biyeun Jan 21, 2025

nospame Jan 22, 2025

nospame Jan 22, 2025

biyeun commented Jan 22, 2025

orangejenny commented Jan 22, 2025

biyeun commented Jan 23, 2025

		return instance.__class__.__name__


		def reports_bootstrap5_template_debugger(report_instance):

		from corehq.motech.repeaters.views import DomainForwardingRepeatRecords


		ALL_REPORTS = [

		@@ -31,6 +31,7 @@ <h5 class="my-2 ms-3">On this page</h5>
		<li><a href="#un-split-view-files">Un-Split View Files</a></li>

[B5] Support for migrating report views to Bootstrap 5 #35648

Are you sure you want to change the base?

[B5] Support for migrating report views to Bootstrap 5 #35648

Conversation

biyeun commented Jan 21, 2025 • edited Loading

Technical Summary

Safety Assurance

Safety story

Automated test coverage

QA Plan

Rollback instructions

Labels & Review

biyeun commented Jan 21, 2025

biyeun Jan 21, 2025

Choose a reason for hiding this comment

biyeun Jan 21, 2025

Choose a reason for hiding this comment

biyeun Jan 21, 2025

Choose a reason for hiding this comment

nospame Jan 22, 2025

Choose a reason for hiding this comment

nospame Jan 22, 2025

Choose a reason for hiding this comment

biyeun commented Jan 22, 2025

orangejenny commented Jan 22, 2025

biyeun commented Jan 23, 2025

biyeun commented Jan 21, 2025 •

edited

Loading